Migrate docs from Docusaurus to Astro/Starlight#507
Merged
alexeyzimarev merged 19 commits intodevfrom Mar 3, 2026
Merged
Conversation
Replace the Docusaurus v3 docs site with a fresh Astro + Starlight setup. Includes: astro.config.mjs with sidebar, Algolia DocSearch, Mermaid plugin, content.config.ts, static assets, and placeholder content pages. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Create ThemedImage.astro and Highlight.astro components - Migrate 32 Markdown files with converted frontmatter (sidebar_position → sidebar.order) - Migrate 12 MDX files with rewritten component imports - Remove DocCardList usage (Starlight auto-generates) - Rewrite ThemedImage to custom Astro component with path strings - Rewrite Highlight import to Astro component - Remove Docusaurus-specific _category_.json files Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Migrate 50 v0.15 doc files with converted frontmatter and component rewrites - Inline MDX partial files into app-service.mdx and func-service.mdx - Re-enable starlight-versions plugin with custom generateId to preserve dots - Add versions content collection with 0.15 sidebar config - 91 pages building successfully (46 current + 45 v0.15) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Update documentation site section to reflect the migration from Docusaurus to Astro + Starlight: new commands, content paths, frontmatter format, and plugin details. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Put starlightDocSearch before starlightVersions so Algolia search takes priority over version-filtered Pagefind - Change code blocks from unsupported "prometheus" language to "txt" (Shiki doesn't support prometheus syntax highlighting) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Starlight requires src/content/docs/index.mdx to serve the root route. Rename intro.mdx → index.mdx and update sidebar to use link: '/' instead of slug: 'intro'. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Move subdirectory/index.{md,mdx} files to subdirectory.{md,mdx} in
parent directory to prevent Starlight from creating unwanted nested
sidebar groups. Consolidate co-located images into section-level
images/ directories. Fix ThemedImage import paths (one fewer ../).
Applied to both current and v0.15 docs.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Switch astro.config.mjs to use logo.png (the actual Eventuous hexagonal logo) instead of logo.svg which contained the Docusaurus dinosaur. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Split the flat sidebar into three collapsible top-level groups: - Concepts: Prologue, Domain, Persistence - Building Apps: Application, Subscriptions, Read Models, Producers, Gateway - Operations: Diagnostics, Infrastructure, FAQ Applied to both current and v0.15 sidebar configurations. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Remove @astrojs/starlight-docsearch in favor of Starlight's default Pagefind search. This eliminates the Search component conflict warnings with starlight-versions and removes the external Algolia dependency. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Replace the docs-first index page with a Starlight splash template featuring a hero section with tagline, logo, and CTA buttons, plus a card grid highlighting key features. Move the previous intro content to a dedicated /intro/ page. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Convert :::type Title to :::type[Title] bracket syntax across all docs (current + v0.15). Map Docusaurus :::info to Starlight :::note. Fixes admonition blocks rendering as raw text. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add collapsed: true to Concepts, Building Apps, and Operations groups in both current and v0.15 sidebar configurations. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Contributor
Review Summary by QodoMigrate documentation from Docusaurus to Astro/Starlight with versioning and component overhaul
WalkthroughsDescription• **Framework migration**: Replaced Docusaurus v3 with Astro 5 + Starlight 0.37 for the documentation site • **Search system**: Migrated from Algolia DocSearch to built-in Pagefind search • **Versioning**: Implemented starlight-versions plugin for managing current and v0.15 archived documentation (dropped v0.14 docs) • **Component rewrites**: Created custom Astro components (ThemedImage, Highlight) to replace Docusaurus theme imports • **Syntax updates**: Converted all frontmatter from Docusaurus format (sidebar_position, weight) to Starlight format (sidebar.order); updated admonition syntax from :::tip Title to :::tip[Title] • **Homepage redesign**: Built new splash template with hero section and feature card grid using Starlight components • **Sidebar restructuring**: Organized navigation into three collapsible sections (Concepts, Building Apps, Operations) • **Content migration**: Migrated all current docs and v0.15 versioned docs with proper path structure and MDX component conversions • **Configuration updates**: Added Astro config, content collections setup, TypeScript configuration, and custom CSS initialization • **Documentation**: Added comprehensive migration and design planning documents for both Docusaurus-to-Starlight and SQLite event store projects Diagramflowchart LR
A["Docusaurus v3<br/>with Algolia"] -->|"Framework & Search"| B["Astro 5 + Starlight<br/>with Pagefind"]
C["Docusaurus Components<br/>ThemedImage, Highlight"] -->|"Custom Rewrites"| D["Astro Components"]
E["Docusaurus Frontmatter<br/>sidebar_position, weight"] -->|"Syntax Conversion"| F["Starlight Frontmatter<br/>sidebar.order"]
G["Docusaurus Versioning<br/>v0.14, v0.15"] -->|"Plugin Migration"| H["starlight-versions<br/>v0.15 only"]
I["Docusaurus Sidebar<br/>Flat structure"] -->|"Reorganization"| J["Starlight Sidebar<br/>3 Collapsible Sections"]
B --> K["92 Pages<br/>Zero Warnings"]
File Changes1. docs/plans/2026-03-03-sqlite-event-store.md
|
Contributor
Code Review by Qodo
1.
|
Deploying eventuous-main with
|
| Latest commit: |
2b9dcd8
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://f8b01a29.eventuous-main.pages.dev |
| Branch Preview URL: | https://migrate-docs-to-starlight.eventuous-main.pages.dev |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Replace legacy /docs links in 0.15 projector docs
These links still point to /docs/..., but this migration serves docs at root/versioned routes (for example the new splash links use /intro/), so clicking these items from the 0.15 “Supported projectors” page now leads to missing pages. Please switch them to version-local relative links (like ../infra/mongodb) or explicit /0.15/... URLs so navigation works inside the 0.15 docs set.
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
![qodo-free-for-open-source-projects[bot]](https://avatars.githubusercontent.com/in/1068000?s=60&v=4){kind=small}
Comment on lines
+6
to
+8
| export default defineConfig({ | ||
| site: 'https://eventuous.dev', | ||
| integrations: [ |
Contributor
There was a problem hiding this comment.
2. Docs base path unclear 🐞 Bug ✓ Correctness
The Astro config does not set a base path, implying root deployment, but the repo still contains /docs-prefixed URLs/redirects and at least one prominent hard-coded root link. Depending on where the site is actually hosted, this will either break existing inbound links (/docs/...) or break site assets/navigation when deployed under /docs.
Agent Prompt
### Issue description
Docs routing appears inconsistent: Astro config implies root deployment, but the codebase still references /docs URLs and includes /docs redirects. This can break navigation/assets depending on hosting.
### Issue Context
- If hosted at `https://eventuous.dev/docs/...`, Astro should be configured with a `base` and content should avoid hard-coded root links.
- If hosted at `https://eventuous.dev/...`, then existing /docs references (READMEs, redirects) should be updated/redirected.
### Fix Focus Areas
- docs/astro.config.mjs[6-69]
- docs/src/content/docs/index.mdx[9-13]
- docs/public/_redirects[1-9]
- src/Kafka/src/Eventuous.Kafka/README.md[1-5]
### Suggested direction
Option A (host under /docs):
- Add `base: '/docs'` in `defineConfig({ ... })`.
- Update homepage hero action link to be base-aware (avoid `link: '/intro/'`; use a relative internal link if supported, e.g. `link: 'intro'`).
- Update `head` favicon href to be base-aware (avoid `href: '/favicon.ico'` if deployed under /docs).
Option B (host at root):
- Update repo references like `https://eventuous.dev/docs/...` to `https://eventuous.dev/...`.
- Consider adding redirects from `/docs/*` -> `/*` to preserve existing inbound links.
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
- Fix ThemedImage component: replace overly-broad :not() selector with explicit dark-only hide/show rules so dark images display correctly - Fix v0.15 supported-projectors: convert hard-coded /docs/ links to relative paths so they work within the versioned docs Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The version switcher on the homepage navigates to /0.15/ which had no index page. Add a splash homepage for v0.15 matching the current one. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Swap content so v0.15 (stable) is the root docs shown by default, and the unreleased preview docs live under the 'next' version slug. Update starlight-versions config with current label 'v0.15 (Stable)' and archived version 'Preview' at /next/. Fix all component import paths after the directory swap. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Override the starlight-versions select width from 6.5em to 10em and restore the full label. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Override Starlight accent CSS variables with the logo's blue (#2563a0) for both light and dark themes. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
starlight-versionsfor version management and built-in Pagefind searchWhat changed
starlight-versionsplugin@pasqal-io/starlight-client-mermaidThemedImageandHighlightrewritten as Astro components:::tip Title→:::tip[Title](Starlight syntax)Test plan
pnpm buildpasses with 92 pages, zero warningspnpm dev)🤖 Generated with Claude Code